home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 301-325 / disk_325 / dclock / dclock.doc < prev    next >
Text File  |  1992-05-06  |  13KB  |  270 lines
  1.                      _                              _
  2.                     //     - DClock v1.12 -        //
  3.                  _ //  * A Dumb Clock Utility * _ //
  4.                  \X/                            \X/
  5.  
  6.                           IMPORTANT NOTICE:
  7.                           -----------------
  8. Due   to   an  important  change  in  the  handler  <->  main  process
  9. communication   structure   DClock   revisions   older  than  1.7  are
  10. incompatible  with this release.  Delete the older files and terminate
  11. the clock process before you install the 1.12 update first!
  12.  
  13.                              BACKGROUND:
  14.                              -----------
  15. Who  cares  for  clock  utilities,  really,  who does?  Well, I do.  I
  16. needed  one,  but  couldn't  find  anything  suitable.   The  standard
  17. Workbench   clock   was  a  bit  too  big,  Mclk  slowed  down  system
  18. performance,  TUC  had  far  too  many  features (including occasional
  19. disk-thrashing),  RSLClock  was  too  large,  so was MachII and DMouse
  20. intentionally didn't have any clock display.  So, what was I up to do?
  21. Right,  I  programmed  my  very  special  creation,  short,  sweet and
  22. functional.
  23.  
  24.                               FEATURES:
  25.                               ---------
  26. Since  I  have already cooked out my custom version of DMouse I didn't
  27. need any additional Mouse accelerator, so this one didn't get into it.
  28. What  I  needed  were  Date (including weekday) and Time.
  29.     The  most important question was:  where to place the display?
  30. Since  I  have  already  tested mouse pointer clocks and my home brewn
  31. MouseClock  program  which  features two sprites hovering at the right
  32. hand  side  of the mouse pointer, the answer could only be:  put it on
  33. the Workbench screen.
  34.     Remembering   my  experiences  with  ReadySoft's  A-Max  Apple
  35. MacIntosh  Emulator  the  time display found its way to the right hand
  36. side  of  the  Workbench  title  bar.  The time string is updated each
  37. second.
  38.     'DClock'  needs  arp.library  v39.1 ('DClock-Handler' doesn't)
  39. and  can  be made resident via the 'ARes' command.  And as far as I am
  40. concerned,  a  memory usage bar can be quite a useful thing.  Pressing
  41. RIGHT-AMIGA+HELP draws some memory statistics into the 'DClock' window
  42. (this  nasty  feature sneaked in in version 1.3, I can't be blamed for
  43. any consequences).
  44.     Mclk  uses  about  10%  of  CPU  time and about 16000 bytes of
  45. memory  (that's  almost  as  much  as  the  standard  Workbench  clock
  46. consumes),  MachII uses 4% of CPU time and 32000 bytes.  'DClock' only
  47. consumes  between  1% and 3% of CPU time and requires only 10000 bytes
  48. of  memory  (well,  became some more during the last revisions, didn't
  49. want  to  change  the text, looks so impressive) - note that this also
  50. includes  the keyboard click, the display beep, the memory display and
  51. the time string to be updated each second.
  52.  
  53.                             INSTALLATION:
  54.                             -------------
  55. Place  'DClock-Handler' in L:, 'DClock' in C:  or SYS:, arp.library in
  56. LIBS:, type "DClock" to install, "DClock quit" to remove.  Easy, isn't
  57. it?
  58.  
  59.                                EXTRAS:
  60.                                -------
  61. 'DClock'  still  isn't  a pure Clock Utility.  I was used to install a
  62. program  called  DisplayBeep  in  my  Startup-Sequence  script.   This
  63. program  spawns  a  process  which replaces the DisplayBeep() function
  64. with a substitute which does not only flash the display but also beeps
  65. audibly.   To  save  some  memory  the  code of DisplayBeep.c has been
  66. incorporated into 'DClock-Handler.c'.  I also added the Click.c code I
  67. had  written back in October.  Somebody asked me to add an alarm-clock
  68. function.  Well, took me two hours to program it.
  69.  
  70.                                 USAGE:
  71.                                 ------
  72. To  start  simply type "DClock" (followed by none or more options) and
  73. press  return.  The main process will be "pulled up" almost instantly.
  74. Note:  if ANYTHING goes wrong on this stage, "DClock" will stop at the
  75. point where "Installing DClock, " appears and nothing else will happen
  76. (the  handler  process has probably died).  "DClock" will wait forever
  77. until you press CTRL-C.  It will shut down and issue an error message.
  78.  
  79. Now  for  the  command  line  options.  'DClock' knows and handles the
  80. following:
  81.  
  82. QUIT .................. Terminates the handler process and removes all
  83.                         loaded data.
  84.  
  85. INFO .................. Gives some information on the current 'DClock'
  86.                         revision.
  87.  
  88. BEEP ON/OFF ........... 'DClock' uses a modified DisplayBeep() routine
  89.                         which  lets  the  usual  display  flash  (e.g.
  90.                         after  the CTRL-G signal) produce a brief beep
  91.                         as  well  as  a flash.  The beep can be turned
  92.                         off this way (default is on).
  93.  
  94. CLICK ON/OFF .......... Each time a key is pressed a keyboard click is
  95.                         produced  (very  similar  to  the high quality
  96.                         style IBM-PC® keyboards).  This feature can be
  97.                         turned off this way (default is on).
  98.  
  99. CLICKVOLUME ........... The  volume  of  the  keyboard  click  can  be
  100.                         adjusted between 0 and 64.  (default is 64)
  101.  
  102. PRIORITY .............. This  determines the handler process priority.
  103.                         Any  number  between  -127  and  127  will do.
  104.                         (default is 5)
  105.  
  106. TEXTCOLOUR ............ The  colour  in  which  the  'DClock' time and
  107.                         memory  display  will  appear  can be adjusted
  108.                         this way.  (default is 0)
  109.  
  110. BACKCOLOUR ............ Same  as  above,  but controls  the background
  111.                         colour.  (default is 1)
  112.  
  113. ALARM ON/OFF/INFO ..... The alarm clock function is controlled by this
  114.                         function.   It can be turned off and on.  INFO
  115.                         displays  the  currently  selected alarm time.
  116.                         (default is off)
  117.  
  118. ALARMTIME HH:MM:SS .... The  alarm  time  is adjusted via this option,
  119.                         note  that  the alarm itself must be turned on
  120.                         separately.  (default time is 12:00:00)
  121.  
  122. REFRESH ...............    Will  reposition  the  DClock display (vScreen
  123.             users:  after the screen size has been changed
  124.             use this option to move the display).
  125.  
  126. SETENV ON/OFF..........    Will  write  the day, date & time to Manx-type
  127.             environment  variables  (DAY,  DATE  &  TIME).
  128.             This   feature  can  be  turned  on  and  off.
  129.             Default is on.
  130.  
  131. QUIET .................    Suppresses all those neat information messages
  132.             which   are   issued  each  time  one  of  the
  133.             abovesaid options is selected.
  134.  
  135. Workbench  users:   'DClock'  can  be  started  from  Workbench!   The
  136. following  tooltype  entries  correspond to the approriate CLI options
  137. and have to appear in capital letters:
  138.  
  139. BEEP,CLICK,CLICKVOLUME,PRIORITY,TEXTCOLOUR,BACKCOLOUR,ALARM,ALARMTIME,
  140. SETENV
  141.  
  142. The  expected  arguments  are the same as with the CLI options.
  143.  
  144.                                CREDITS:
  145.                                --------
  146. Credits  go  to ARP Programmers for the most recent version of ARP, to
  147. Matt  Dillon  for  DMouse,  to  Mike  Oldfield  & Peter Norman for the
  148. keyboard  click,  to Mason/Waters/Wright/Gilmour/Parsons for the alarm
  149. clock  sound, to John Hodgson for the beep and to Justin V.  McCormick
  150. for the string formatting code.
  151.     A  special mention must also go to Bill Hawes, author of ARexx
  152. and  to  the  authors of CygnusEd Professional 2 (Bruce Dawson & Colin
  153. Fox) whose programs both controlled the compiler runs.
  154.  
  155.                    COPY FEE, AUTHORS REQUEST, ETC.:
  156.                    --------------------------------
  157. If  you  like  'DClock' and wish to contribute any money I urge you to
  158. send at least 5$ to...
  159.  
  160.                         Amnesty International
  161.                             P.O. Box 37137
  162.                         Washington D.C. 20013
  163.  
  164. I  suppose Amnesty International can make better use of the money than
  165. I can.  Even the smallest contribution makes sense.
  166.  
  167. I don't care what happens to 'DClock' and 'DClock-Handler', copy them,
  168. sell them, delete them, they are meant to be PUBLIC-DOMAIN.  But don't
  169. 'fleece'  other  users  for  them.   Permission  to  redistribute  the
  170. documentation, the source code and executable files granted as long as
  171. the body of this document is left intact.
  172.  
  173.                                   -
  174.  
  175. I have tried to make 'DClock' as flexible as possible.  The rendezvous
  176. data  is  easily  to  be  extended.   I  encourage you to add whatever
  177. feature  you  want.   I  only ask you to send me a copy of your custom
  178. version  of  'DClock'.  The future of this tool depends on you, spread
  179. the word and also the disk!  My address is:
  180.  
  181.                              Olaf Barthel
  182.                           Brabeckstrasse 35
  183.                           D-3000 Hannover 71
  184.  
  185.                      Federal Republic of Germany
  186.  
  187.              REVISION HISTORY (most recent change first):
  188.              --------------------------------------------
  189. V1.12    I 'ripped' the PopRequest routine from my programmers' library
  190.     (mxm.library)  and integrated it into the DClock.c code.  This
  191.     will  display  real error messages ever so often the Workbench
  192.     tool  info parsing routine stumbles upon an error.  Note also:
  193.     I've   quit  the  Electronic  Design  Hannover  team  and  the
  194.     copyright  changes  to  MXM.   A  note on the code (whoops, it
  195.     rhymes!):   the pop-up requester part may be incorporated into
  196.     any program which has any need of it.  If the CED Professional
  197.     update  had  reached  us earlier the req.library pop-ups would
  198.     have  been  employed  instead of my requesters.  It's too late
  199.     now,  I  don't  want  to  change the code any more and anyway:
  200.     some  of  you might think that 30 libraries (that's as much as
  201.     there  are  in my LIBS:  drawer) are enough and will prefer to
  202.     use the non-library code instead.
  203.  
  204. V1.11    Wow!   The  display  found its way back to the Workbench title
  205.     bar -> with the fastest refresh scheme possible.  This is done
  206.     via  rendering  into  an  invisible  RastPort;  this  image is
  207.     transferred  to  the  Workbench bar layer.  Now also included:
  208.     display  will  move  to  the  left  hand  of  the screen depth
  209.     arrangement gadgets after the REFRESH option is selected.
  210.  
  211. V1.10    Better   Workbench  support added (older revision preferred to
  212.     crash  too  often and didn't notice if Workbench was re-opened
  213.     after  closing  the  last  custom screen).  DClock window will
  214.     auto-adjust  its  position  to appear at the left hand side of
  215.     the  screen  depth  arrangement  gadgets  (a  special gift for
  216.     overscanned Workbench screens - merry Christmas, it's the 22nd
  217.     of December 1989!).
  218.  
  219. V1.9    Full  Workbench  support  added (oh boy, I am tired!).  I will
  220.     try to supply a neat icon to get it working.
  221.  
  222. V1.8    CloseWBench()/OpenWBench()  support  available  now!  'DClock'
  223.         will  close  its  window  just  in time to allow the Workbench
  224.         screen  to  be  closed.  It will re-open its window as soon as
  225.         the Workbench screen has successfully been re-opened.  New for
  226.         single-bitplane  Workbench  (soon  to  come in Kickstart 1.4):
  227.         memory  gauge  will  display a shaded bar instead of an orange
  228.         one.
  229.  
  230. V1.7    Some  cosmetical  changes,  no  spectacular  work  done; well,
  231.         except  for the small bug fix in the alarm routine (alarm only
  232.         worked  if  time  display was active).  Docs partly rewritten,
  233.         cleaned  up  some  code.   Important:   added  new DSeg entry:
  234.         RingBack  ->  no  downward  compatibility  with older 'DClock'
  235.         revisions  guaranteed  anymore (sorry, but this was absolutely
  236.         necessary).
  237.  
  238. V1.5    Added  a  most  unnerving  alarm  clock function:  the display
  239.         vibrates,  a  bell  is  ringing ...  what can it be?  Probably
  240.         'DClock' trying to wake you up.
  241.  
  242. V1.4    Fixed  bug  in  time  signal routine (didn't update if seconds
  243.         were  reset  to  a point of time already passed), added status
  244.         line information, corrected exit() calls in 'DClock'.
  245.  
  246. V1.3    Played  around  with  a  taller custom font (saw Kickstart 1.4
  247.         alpha  15  and  noticed  that the Workbench status line became
  248.         longer overrriding the 'DClock' display).  The font didn't get
  249.         into it.  Added a numeric memory display.
  250.  
  251. V1.2    Thought  of  incorporating  the  code of Click and DisplayBeep
  252.         into  'DClock'  and  added  them.   Also  stumbled upon my old
  253.         MemGauge program and added a memory gauge display.
  254.  
  255. V1.1    Added  ARP  interface,  replaced  standard  DOS calls with ARP
  256.         calls,  removed  the  clock  display from the barlayer (always
  257.         crashed  after  a  call  to  CloseWorkBench()),  added weekday
  258.         conversion and command line options.
  259.  
  260. V1.0    Simple  ('dumb')  backdrop clock with date and time display to
  261.         be rendered directly into the Workbench bar layer.
  262.  
  263.                                   *
  264.  
  265.              Do only its possibilities make it an Amiga?
  266.  
  267.                         WHERE IS THE MAGIC ???
  268.  
  269.  P.S.: Lattice, where is the 5.04 compiler update we are waiting for?
  270.